• Tutorials

This section provides step-by-step instructions to help you perform many common tasks using maX.500. 
 Setting up maX.500
If you have a network connection and the Apple MacTCP control panel is properly installed, maX.500 should work without any additional setup on your part.  If you are affiliated with the University of Michigan and want to authenticate to X.500 using your uniqname and Kerberos password, the Authentication Manager control panel (AuthMan) must be installed on your Macintosh.  If you are upgrading from version 2.0 of maX.500, you should install the version of AuthMan included with this version of maX.500.  See the next tutorial topic for step-by-step instructions for installing the Authentication Manager.

When maX.500 starts up, it will open a maX.500 News window. By default it will also open a command palette that has four icons labeled Find, Browse, Help, and Authenticate. The icons act as buttons to invoke four commonly used maX.500 functions.   The Find Entry window will be opened just to the right of the command palette.

If you wish to change maX.500's default behavior, choose Preferences… from the File menu.  See the Preferences topic in the Reference section of this online help for detailed information about the various options.

 Installing the Authentication Manager

The Authentication Manager control panel (AuthMan) version 1.0.7 is distributed with maX.500 2.0.1, so you should already have a copy.  If you do not have a copy, contact the ITD Consultants by phoning 764-HELP or sending an e-mail message to online.consulting@umich.edu.  To install the AuthMan control panel, follow these steps:

Step 1: Drag the control panel file “Authentication Manager” to the System Folder.

Step 2: Reboot your Macintosh.  You can now open the control panel to change various settings, but you shouldn't really need to do so (most of the settings have to do with Kerberos realms and servers; it should already be set correctly for U-M campus).

Step 3: Open the Map control panel to check the time zone setting.  There are two boxes and a checkbox to the right of the Time Zone label.  If you are on Eastern Standard Time, the time zone offset should be 5h 0m and the box labeled + should not be checked.  If you are on Eastern Daylight Savings Time, the offset should be 4h 0m (box labeled + unchecked).  Click once on the Set button, and close the Map control panel.

Step 4: Open the General Controls control panel and set the time of day to be within 5 minutes of the correct time.  If you are in Ann Arbor, Michigan you can phone 665-1212 to get a recording of the correct time.  Make sure the date is correct as well.

• Special note for users of System 7.1 Pro (and later System Software versions): the Date & Time control panel has been expanded to include the ability to set the time zone by picking a city in your time zone, and there is now a checkbox that you can use to indicate whether you are currently in daylight savings time.  Steps 3 and 4 above can be replaced by:  Use the System 7.1 Pro Date & Time control panel to set your time zone, indicate if you are on daylight savings time or not, and to set the correct time of day and date.

You can test the AuthMan installation by trying to authenticate as yourself; see the topic “Authenticating to the X.500 Directory” below for more information.

 Finding someone
This tutorial steps you through the process of finding a person at U of M.

Step 1: Open and/or bring the Find Entry window to the front by choosing Find Entry from the Directory menu, clicking the Find icon on the command palette, or by pressing ⌘-F.  A small window entitled Find Entry should be visible with a button at the lower left labeled “More Choices.”  If it says “Fewer Choices”, click the button once to return to a simpler version of the Find Entry window.

Step 2: Use the Find popup menu to choose the type of entry you want to find.  By default, it should say “Find people”, so you may not need to do anything.  The steps outlined here work for finding other kinds of entries, such as groups; you just need to choose the appropriate type from the Find popup menu.  As a shortcut, you can press and hold the ⌘ and SHIFT keys and then type the first letter of the type of entry you want to find.  For example, ⌘-SHIFT-G will change the Find popup menu to “groups.”

Step 3: Choose where you want to search (this is called the searchbase).  The current setting is shown next to the words “Look Within:” and is probably University of Michigan, US if you have not changed it.  This means search the entire University of Michigan portion of the X.500 Directory.  To learn how to set the searchbase, see the topic “Choosing where to search” later in the Tutorials section.  For now, you can leave it set to the default.

Step 4: Type something that describes the person you want to find.  In the search for box, you can actually type any of the following:
 • a full name, e.g., Babs Jensen
 • just a last name, e.g., Jensen
 • a uniqname or login, e.g., bjensen
 • first initial and last name, e.g., b jensen
 • first name and last initial, e.g., babs j
 • the last few digits of a telephone number, e.g., 74454
 • an e-mail address, e.g., bjensen@terminator.rs.itd.umich.edu
 • an explicit LDAP search filter, e.g., sn=jensen (probably only useful if you are an X.500 expert!)

Step 5: Click the Find button (or press the return or enter key);  maX.500 will perform the search you requested.  If exactly one match is found, that entry will be retrieved and shown.  If there are several matches, you will be asked to choose one to view.  If there is no match or an error occurs, you will be informed with an alert message.  Note that if what you typed does not exactly match anything in the directory, maX.500 will automatically try approximate and other less exact searches for you.  You can check the Exact Match Only checkbox to turn off the automatic use of approximate searches.

 Viewing an entry
When you have successfully found something, maX.500 displays an X.500 Information window that contains information about that directory entry.  The window will be titled something like UM Person – Babs Jensen.  Along the top, directly below the title, a friendly representation of the full X.500 Directory name (known as the “Distinguished Name”) of the entry is shown.  Entry names are globally unique (and thus a bit lengthy).

Most X.500 Info windows have a row of buttons along the top of the window that you can press to do things such as view a photo or listen to an audio clip (if the entry has either of those).  Some buttons are links to other windows (an example is the Updates… button that allows you to specify whether your entry should be updated from the Personnel or Registrar databases).  As a shortcut, you can press and hold the ⌘ and SHIFT keys and then type the first letter of a button title to activate it.  For example, ⌘-SHIFT-G is equivalent to clicking the Groups… button with the mouse.

Directory entries consist of fields (called “attributes” in X.500 parlance) with values.  An example of a field is “Business Phone.”  It may have zero, one, or several values (e.g., +1 313 764-4357).  If a field contains single line values (like phone numbers), multiple values are simply listed one per line.  If a field contains multi-line values (such as a street address), values are separated by blank lines.

Most X.500 Info windows in maX.500 follow the convention that field names appear in a column along the left side of the window, and values appear to the right of the field names.  To edit the values, click to the right of the field name (that is, click on the values).  For more information about editing your entry, see the tutorial topic “Changing your entry” later in this section.

Some values are special in that they point to other entries in the X.500 Directory.  These values have a small, shadowed, right-pointing arrow next to them.  To view the entry pointed to, simply click once on its arrow.

 Choosing where to search
The X.500 Directory is worldwide, and it is organized in a tree-like fashion.  Below the root of the directory there are countries (such as the United States or Great Britain).  The structure beneath each country varies, but it is generally made up of organizations (such as NASA) and states (such as Michigan).  Generally, you can search an entire organization (penetrating all the way to its furthest depths), but you cannot search an entire country in the same manner.  In maX.500, the location where the next Find Entry command (or other search) will take place is called the Searchbase.

To set the searchbase in maX.500, perform the following steps:

Step 1: Open the searchbase browser dialog by choosing Browse… from the Searchbase menu, by pressing ⌘-B, or by clicking on the Browse (globe) icon on the command palette or Find Entry window.

Step 2: Manipulate the list, Searchbase popup menu, and the buttons in the Browse dialog to find the organization you want to search.  Descriptions of the items follows:

 • The top portion of the dialog contains a list of the items that are located at the current level.  Note that in maX.500 2.0.1, “leaf nodes” are omitted, so you will not see people or other objects in this list.  Click on an item in the list to select it, and then use one of the buttons to take an action.
 • The Cancel button closes the Browse dialog without changing your searchbase.
 • The Current Level button sets the item shown in the searchbase popup menu as the new searchbase, and closes the Browse dialog.
 • The Selected Level button sets the item selected in the list as the new searchbase, and closes the Browse dialog.
 • The Open button moves down into the item selected in the list, and presents a new list of items that are within.  Double-clicking an item in the list is equivalent to Open.
 • Directly above the row of buttons is a Searchbase popup menu that shows the current level being browsed.  Choosing an item from the menu allows you to quickly move up the directory hierarchy.

Note that there are some pre-configured Searchbases available in the bottom portion of the Searchbase menu.  Choosing one of these directly sets the Searchbase without requiring use of the Browse dialog.  Some of the items also change the Find popup menu to indicate the kind of entry to find (e.g., people or groups).
 
 Searching using “User Friendly Naming”
It is inconvenient to always have to use the Browse command to choose where you want to search.  User Friendly Naming was developed to address this problem.  If you are using the simpler “Fewer Choices” Find window (recommended), you can enter something that contains a comma in the Find Entry window to have it interpreted as a User Friendly Name (UFN).  UFNs are of the form:
    name, organization, country                  or
    name, organization, state, country
Note that the country and state can be abbreviated.

Some examples:
tim howes, um, us
   (find Tim Howes within organizations known as “um” within the United States)
rose, dover beach consulting, california, usa
   (find someone with last name Rose who works for a California-based consulting company)
rose, dbc, ca, usa
   (a shorter way to find Rose)
robbins, nexor, britain
   (find someone with last name Robbins who is at an organization called “Nexor” in Great Britain)

Note that unchecking the “Use UFN Search” box in the Preferences dialog will disable UFN searching entirely.  UFN is convenient, but has some limitations.  In maX.500 2.0.1, the setting of the Find popup menu is ignored when UFN search is invoked.  You may get people, groups, or anything in response to a UFN search.  Also, the search is not as smart – the left-most part of the UFN string must be a full name or uniqname/login or last name.  More exotic things like phone numbers will not work.

 Searching within an organization
This topic describes another way to set the searchbase (the area you want to search).  The basic idea is to perform an extra search to find the organization you would like to search.  This process involves several steps:

Step 1: Set your Searchbase to the country or state where the organization you wish to search exists.  It is probably easiest to use the Browse command, as described in the earlier section called “Choosing where to search.”  However, if the organization is in the US, you can simply choose United States from the Searchbase menu.

Step 2: Open and/or bring the Find Entry window to the front by choosing Find Entry from the Directory menu, clicking the Find icon on the command palette, or pressing ⌘-F.

Step 3: Set the Find popup menu to organizations.

Step 4: Type the name of the organization you want to search within and press the Find button.  maX.500 will (hopefully) find the organization you are looking for, and display it in an X.500 Information window.  Note that most organizations list their abbreviated names in addition to a full formal name.  For example, “umich”, “um”, and “university of michigan” will all find “The University of Michigan.”

Step 5: Choose Find Within This Entry from the Directory menu.  The Find Entry window will be brought to the front, and it will now show a searchbase (next to “Look within:”) corresponding to the organization.  You can also set the searchbase by clicking on the “Find Within” icon located directly above the vertical scrollbar in the organization's X.500 Info window.  The icon has a person's face with a ? next to it (it is a tiny version of the Find icon found on the command palette).

Step 6: Change the Find popup menu to reflect the type of entry you are looking for (e.g., person) and proceed to specify and carry out your search as described above in “Finding someone.”

 Authenticating to the X.500 Directory
Simply put, authenticating is the process of identifying yourself to the X.500 Directory.  Much of the information stored in X.500 is readable by everyone, but authentication is always required to save changes to entries or to add new entries to the directory (such as groups you define).  This topic explains how to explicitly authenticate, but note that it is usually not necessary to do so.  You will be prompted to authenticate when it is required.  For example, if you make changes to an entry on the screen and try to save them, maX.500 will bring up the Authenticate dialog for you.

Note that if you are at U of M and you want to authenticate using your uniqname and Kerberos password, the Authentication Manager (AuthMan) control panel must be installed on your Macintosh.  Refer to the topic “Installing the Authentication Manager” above for installation instructions.  Note that maX.500 and AuthMan do not currently support changing your Kerberos/uniqname password.

Choosing Authenticate… from the Directory menu, pressing ⌘-U, or clicking the Authenticate icon on the command palette (it looks like a skeleton key) will bring up the Authenticate dialog.  You will be prompted to enter your name, uniqname, or an “Entry name.”  There may be a default name entered for you.  An entry name is an X.500 Distinguished Name (which can be obtained from an X.500 information window using Copy Entry Name from the Edit menu).  Most of the time you will just type your name or Uniqname and press the Authenticate button.  maX.500 will then search for a person that matches what you typed.  The search used is actually the same search used in the Find Entry window, so you can enter your name, uniqname, phone number, or even a “User Friendly Name” to identify yourself.

Next you may be asked to Choose an Authentication Method.  maX.500 supports both simple X.500 password and Kerberos/uniqname password authentication.  You may be asked to choose from a list of different Kerberos names (such as uniqname@umich.edu and uniqname@engin.umich.edu) and possibly an X.500 Password if you have one.

After choosing a method, you may be prompted for a password.  If you have already authenticated using your uniqname and password (the Campus Computing Sites require these to gain access to the Macintoshes), you will not be asked again for your password.

If an error occurs, a message will be displayed (otherwise the authentication was successful).

 Changing your entry
After finding an entry, you can make changes to some fields.  At U of M, most people only have permission to change their own entry and the entries for any groups they have created.  You may not have permission to change certain fields, such as your name.  These fields may require you to go through some kind of administrator to make a change.  For example, if you are affiliated with the University of Michigan and want a nickname added to your entry, send electronic mail to nicknames@umich.edu and a person will make the change for you.  Enclose your University ID number (usually the same as your Social Security Number) or uniqname to ensure proper identification.

Note that maX.500 does not currently support editing some complex fields, including images and sounds.

To make changes to an entry:

Step 1: Find the entry you want to change (see the topic “Finding someone” near the beginning of the Tutorials section).  Ensure that the X.500 Information window for that entry is the active window.

Step 2:  Begin editing the field you want to change and enter “edit mode” by doing one of the following:
 • click to the right of the label of the field (that is, click on the values).  For example, if you want to add or change an e-mail address, click to the right of the field labeled “E-Mail Address.”  Note that when the cursor is over something you can click on to edit, it will change to a text insertion “I” beam. 
 • click on the field label itself.  This selects the entire field.
 • choose Edit Entry from the Edit menu, or press ⌘-E.  The first editable field in the entry will be selected, and a check mark will appear next to the menu item.  You can choose Edit Entry a second time to leave “edit mode.”

Step 3: Make your changes to the field using the keyboard and mouse.  Repeat Step 2 to edit as many fields as needed.  If you are at the University of Michigan, be sure to click on the Updates… button (located along the top of the window) to read an important message about changing fields that are also held by Personnel or the Registrar.

Step 4: When you are done making changes, choose Save Entry from the File menu, or press ⌘-S.  maX.500 will ask you to authenticate (if you have not already done so).  See the topic, “Authenticating to the X.500 Directory,” for detailed information.  After you authenticate, the changes you made will be written to the X.500 Directory.  If maX.500 is unable to save the entry for some reason, an error message will be displayed.

 Groups
 
Introduction
maX.500 2.0.1 supports the creation and maintenance of groups of people (or groups containing other groups) in the X.500 Directory.  The most common use of a group is for electronic mail purposes.  At the present time groups (as maX.500 knows them) have only been implemented at the University of Michigan.

Finding groups is similar to finding people – just set the Find popup menu in the Find Entry window to “groups” or “joinable groups.”  (See the topic “Finding Someone” near the beginning of this Tutorials section for more information about the Find Entry command.)

Groups can contain two kinds of members: X.500 Members and E-Mail Members (either of which can be a person or another group).  Adding people (or other groups) as X.500 Members is preferred.  X.500 Members are stored as references to the member's X.500 entry, and X.500 entry names do not tend to change.  An E-mail Member is stored as an Internet e-mail address (e.g., tim@terminator.rs.itd.umich.edu).  Since not everyone in the world who has e-mail is in the X.500 Directory yet, you may need to use E-Mail Members for some people.

If a group is named “abc letters” then e-mail addressed to abc.letters@umich.edu will be delivered to all the members of the group.  Note that group names should not contain periods (.) because, for e-mail purposes, the X.500 software will automatically recognize periods where you put spaces.  Note that short group names (three to eight characters) may conflict with people’s uniqnames, and maX.500 will warn you if you attempt to create a group with such a name.  If you really want to use such a name, you should talk to your uniqname administrator about reserving it.

Each group can contain two special elements:  an “errors to” and a “requests to” address.  Each of these can be an X.500 entry reference or an e-mail address.  If any errors occur while delivering to the group, they will be sent to the “errors to” address.  This can be used to avoid sending error reports to all the members of a large group.  E-mail sent to abc.letters-request@umich.edu will be sent to the “requests to” address.  This makes it easy to support the convention that “-request” appended to a group address will be sent to someone who takes care of adding and deleting people from the group.

Groups can be created such that all of the group members are contained in the group entry itself and maintained by one or more owners of the group or they can be set up so others can join the group.  The list of groups a person is subscribed to is stored with that person's entry, not with the group itself. 

By default, groups are not moderated:  anyone may send a message to the group address and it will be sent to the entire group membership.  You can moderate a group by entering one or more e-mail addresses in the group’s “Moderated By” field.  Once that is done, a message that comes from any of the moderator addresses is sent to the entire group, but other messages are sent only to the moderators.  They can then filter out e-mail that is not appropriate for everyone in the group to receive (such as subscribe requests that are not sent to the -request address but should’ve been).

 Joining a group
You can join a group either from your own entry or from the group entry.

Method 1 – Joining from your own entry:

Step 1: Find your entry.  (See the tutorial topic “Finding Someone” for more information.)

Step 2: Click the Groups… button near the top of your entry window.  A second X.500 Info window entitled “UM Person Groups” will open.

Step 3: Click the Join a Group… button.  The “Join Groups” dialog will appear.

Step 4: Type a list of groups you would like to join, and click the Find and Join button (or press ⌘-F).  maX.500 will search for the groups and (as it finds them) add them to your “Subscribed To:” list.  The search is the same search used in the Find Entry window.

Step 5: Save your entry to permanently store the new information in the X.500 Directory.

If maX.500 has trouble finding groups that you know are in the X.500 Directory, double check your searchbase.  For example, if the searchbase is set to confine the search to the People area, no groups will be found.  It is often easiest to leave the searchbase set to an entire organization (e.g, University of Michigan, US).

Method 2 – Joining from the group's entry:

Step 1: Find the group (this is most easily done by searching for joinable groups).

Step 2: Click the Join… button located near the top of the group window.  You will be asked to Authenticate if you have not already done so.  Be sure to authenticate as the entry you want added to the group.  The group's X.500 name will then be added to the “Subscribed To:” list of that entry.  If an X.500 Info window for that entry is open on the screen, you will need to save the entry to make the change permanent; otherwise the change is immediately written to the X.500 Directory. 

 Resigning from a group
Step 1: Find your entry.  See the tutorial topic “Finding Someone” for more information.

Step 2: Click the Groups… button near the top of your entry window.  A second X.500 Info window entitled “UM Person Groups” will open.

Step 3: Click on the name of the group.  Choose Edit Entry from the Edit menu, or press ⌘-E to edit the “Subscribed To:” list.

Step 4: Delete the entire line containing the group name.

Step 5: Save the entry by choosing Save Entry from the File menu, or by pressing ⌘-S.

 Listing groups
You can list groups that you have been explicitly added to by the group owner, and groups that you own.

Step 1: Find your entry.  See the tutorial topic “Finding Someone” for more information.

Step 2: Click the Groups… button near the top of your entry window.  A second X.500 Info window entitled “UM Person Groups” will open.

Step 3: Click the Find Groups Added To… button or the List Owned Groups… button.  maX.500 will search for the appropriate groups and present a list.  You can select a group from the list and click the View Entry button to view the group entry.

 Creating a new group
If you have a uniqname and Kerberos password, maX.500 will allow you to add groups that you own and maintain to the X.500 Directory.  The steps are:

Step 1: Choose New Entry… from the File menu, or press ⌘-N.  If you have not already authenticated, maX.500 will prompt you to do so.

Step 2: The New Entry window will appear.  Choose group from the “Choose the type of entry to add” list.

Step 3: Click in the Entry Name: text box (or press the tab key), and type the name of the group you would like to add.  Note that if you use periods (.) or underscores (_) to separate multiple words in the name, maX.500 will translate them to blanks.  For e-mail purposes, the X.500 software will automatically recognize periods and underscores where you put spaces, i.e. a group named “test group” will receive e-mail sent to either test.group@umich.edu  or test_group@umich.edu.

Step 4: Click the OK button (you should not need to change the location where the group is to be created).  The New Entry window will go away, and a New Group window X.500 Info window should open.

Step 5: Fill in additional information about the group, and then choose Save Entry from the File menu (or press ⌘-S) to save the new group.  Note that maX.500 has filled in default values for several fields, but you can change them.  A brief description of each of the fields that may be present in the group follows:

 • Also Known As:  the name or names by which you want the group to be known.  You should not remove the original name given when you created the group.

 • Description:  a short text description of the group and its purpose.

 • Owner:  the X.500 names or names of the people who can make changes to this group.  These are the maintainers of the group.

 • Last Modified: and Modified By: the date and person who last changed the group entry.  You cannot edit these fields; they are automatically maintained.

 • Send Errors To:  the X.500 Name of the people to which delivery errors should be sent.

 • Requests To:  the X.500 Name of the people to which e-mail addressed to groupname-request is to be sent.

 • Assoc. Domain:  the Internet domain with which this group is associated.  It should be umich.edu for all groups that are to be addressed as:  groupname@umich.edu.

 • Moderated By:  e-mail addresses of those who can send messages to the entire group (the moderators).  If this is empty, the group is not moderated and all e-mail sent to the group is sent to the entire group membership.  If moderators are listed, e-mail sent to the group from one of the moderator addresses is sent to everyone, but other e-mail is sent only to the moderators.  This can be used to filter out inappropriate messages.

 • Allow Others To Join This Group (checkbox):  if this box is checked, others can join this group.  If not, only the X.500 and E-mail Members added by the group owners will be members of the group.  Click the List Subscribers… button to bring up a list of all those who have subscribed to a group.

 • X.500 Members:  the X.500 Names of the group members.  See the next section “Adding people to a group” for more information on how to populate this field, including the use of the Add… button.

 • E-mail Members:  the Internet-style addresses of group members who do not have X.500 entries.  Internet addresses are of the form name@domain (e.g., bjensen@terminator.rs.itd.umich.edu).

 • E-mail Errs. To:  the e-mail address counterpart to the “Send Errors To” field.  Use this only if you need to have delivery errors sent to someone who does not have an X.500 entry.

 • E-mail Reqs. To:  the e-mail address counterpart to the “Requests To” field.  Use this only if you need to have “-request” mail sent to someone who does not have an X.500 entry.

• Notice: one line of text that can be used to tell people late-breaking information about the group.  The intent is that this would be displayed as someone was sending a message to the group, although most e-mail clients do not yet do that.

 Adding members to a group
The easiest way to add members to a group is to use the Add… button located beneath the “X.500 Members” label.  Note that you can add people or other groups as members of another group.  If the members of your group are not in the X.500 Directory, you should instead directly type their e-mail addresses in the “E-mail Members” field.

The steps to add X.500 Members to a group are:

Step 1: Find the group entry.  (See the tutorial topic “Finding Someone” for more information.)

Step 2: Click the Add… button.  The “Add X.500 Members” dialog will appear.

Step 3: Set the “Enter a list of … to Add:” popup menu as appropriate to add people or groups.

Step 4: Enter a list of people (or groups) you would like to add and click the Find and Add button (or press ⌘-F).  maX.500 will search for the people (or groups) and enter them as it finds them into the group's “X.500 Members:” field.  The search is the same search used in the Find Entry window, so you can enter names, uniqnames, phone numbers, or even “User Friendly Names” to identify the members.  Check the Exact Match Only checkbox if you do not want maX.500 to use approximate searches to try to find people or groups.

Step 5: To save the new entry and store the information in the X.500 Directory, choose Save Entry from the File menu (or press ⌘-S).

If maX.500 has trouble finding people or groups that you know are in the directory, double check your Searchbase.  For example, if you are adding people and the Searchbase is set to confine the search to the Groups area, the people will not be found.  It is often easiest to leave the Searchbase set to an entire organization (e.g., University of Michigan, US).

 Removing members from a group
To remove members, simply delete the entire line containing them from the “X.500 Members” field (or delete their e-mail addresses from the “E-mail Members” field).  Be sure to save the entry after removing members.

 Deleting a group
To completely remove a group (after it has served its purpose), find the group and choose Delete Entry from the File menu.  When you delete a group it is permanently removed from the X.500 Online Directory and there is no way to restore the group membership.